<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<html>
<head>
<title>jqMock API</title>
<link type="text/css" rel="stylesheet"  href="jqMock.css" />
<link type="text/css" rel="stylesheet" href="highlighter/SyntaxHighlighter.css" />
</head>
<body>
<h1>jqMock API</h1>

<ul id="nav">
	<li><a href="http://code.google.com/p/jqmock/">Home</a></li>
	<li><a href="download.html">Download</a></li>
	<li><a href="userguide.html">UserGuide</a></li>
	<li><a class="current">API</a></li>
	<li><a href="faq.html">FAQ</a></li>
	<li><a href="../src/jqMock.html">Tests</a></li>
	<li class="last"><a href="http://users.tpg.com.au/fuzziman/jqmock/jscoverage/jscoverage.html?jqMock.html">Coverage</a></li>
</ul><br style="clear:both;"/>

<ul>
<li><a href="#jqmockns">jqMock namespace</a></li>
<li><a href="#jqmockmock">jqMock.Mock</a></li>
<li><a href="#modifier">Modifier</a></li>
<li><a href="#MultiplicityFactory">MultiplicityFactory</a></li>
<li><a href="#ExpressionFactory">ExpressionFactory</a></li>
</ul>

<h2><a name="jqmockns">jqMock namespace</a></h2>
<table class="api">
<tr><th>Function</th><th>Description</th></tr>
<tr>
<td>jqMock.Mock(obj, fnName)</td>
<td>constructor, creates a Mock on the function obj.fnName</td>
</tr>
<tr>
<td>jqMock.assertThat(actual, expected [, msg])</td>
<td>assertion which allows you to use expressions as the expected argument. Message is optional.</td>
</tr>
<tr>
<td><a name="expectThatExceptionThrown" class="ref">jqMock.expectThatExceptionThrown(Function, expected)</a></td>
<td>assert that an expression will be thrown when the Function block is executed, and that it matches the expected argument. 
The expected argument can be:
<ul>
<li><b>a value or an expression</b> will perform assertThat(ex, expected). These is also a special expression for matching exceptions, see <a href="#isexception">is.exception()</a></li>
<li><b>{name:string, message:string, type:Class}</b>  asserts ex.name and ex.message, and that ex instanceof Class. You can provide any or all of these 3 attributes.</li>
</ul>
</td>
</tr>

<!--
<tr>
<td>jqMock.tostring(obj)</td>
<td>creates string representation of an object. this is in json notation, although function bodies are not printed out.<span class="warning">Don't use with objects that have circular references, as it will cause infinite recursion and crash.</span></td>
</tr>
-->
<tr>
<td>jqMock.expect</td>
<td>alias to MultiplicityFactory, which gives you multiplicity objects.</td>
</tr>
<tr>
<td>jqMock.is</td>
<td>alias to ExpressionFactory, which gives you Expression objects.</td>
</tr>
<tr>
<td>jqMock.addShortcut()</td>
<td>copies <b>jqMock.expect</b> and <b>jqMock.is</b> to the global namespace.</td>
</tr>
</table>



<h2><a name="jqmockmock">jqMock.Mock</a></h2>
<table class="api">
<tr><th>Function</th><th>Description</th></tr>
<tr>
<td>modify()</td>
<td>returns a Modifier object, which represent a single expectation. See the section <a href="#modifier"> Modifier</a> on how to setup the expectation.</td>
</tr>
<tr>
<td>setOrdered(boolean isOrdered)</td>
<td>whether the mock will use ordered expectation</td>
</tr>
<tr>
<td>verify()</td>
<td>verfies whether the expectations have been satisfied, recording the results into the jqUnit framework.</td>
</tr>
<tr>
<td>reset()</td>
<td>removes all expectations and resets all counts, but leave the interception. allows a mock to be reused.</td>
</tr>
<tr>
<td>restore()</td>
<td>call reset(), and removes the interception</td>
</tr>
</table>
<p>Example:</p>
<pre name="code" class="js:nocontrols:nogutter">
	var confirmMock = new jqMock.Mock(window, "confirm");  
	confirmMock.setOrdered(true);

	confirmMock.modify().args("are you sure?").returnValue(true);  
	window.confirm("are you sure?"); 
	confirmMock.verify(); 
	confirmMock.reset();

	confirmMock.modify().args("are you still sure?").returnValue(false);
	window.confirm("are you still sure?"); 
	confirmMock.verify(); 
	confirmMock.restore();
</pre>
<br/><br/>




<h2><a name="modifier">Modifier</a></h2>
<table class="api">
<tr><th>Function</th><th>Description</th></tr>
<tr>
<td>args(x1,x2,x3,...)</td>
<td>The expectation is matched using these arguments, can be any number of arguments. Arguments may be of any type, or may be an Expression.</td>
</tr>
<tr>
<td>multiplicity(number)</td>
<td>Number of times you this expectation should match. A number parameter means exactly that number of times.</td>
</tr>
<tr>
<td>multiplicity(Multiplicity)</td>
<td>Number of times you this expectation should match, parameter is a Multiplicity object. You get Multiplicity objects by calling a method on the <a href="#MultiplicityFactory">MultiplicityFactory</a>.</td>
</tr>
<tr>
<td>returnValue(rv)</td>
<td>Intercept the method, and return the given parameter instead.</td>
</tr>
<tr>
<td>throwException(ex)</td>
<td>Intercept the method, and throw the given parameter as an exception.</td>
</tr>
</table>
<p>Example:</p>
<pre name="code" class="js:nocontrols:nogutter">
	var mock = new jqMock.Mock(myobj, "fn");  
	mock.modify().args('a', is.not('a'));
	mock.modify().multiplicity(3);  // when args() not used, defaults to no args
	mock.modify().args('a').multiplicity(expect.atLeast(3));
	mock.modify().args(1,2,3).returnValue(true);
	mock.modify().args({foo: 'bar'}).throwsException(new Error('boo'));;
</pre>
<br/><br/>



<h2><a name="MultiplicityFactory">MultiplicityFactory</a></h2>
		
<table class="api">
<tr><th>Function</th><th>Description</th></tr>
<tr>
<td>exactly(n)</td>
<td>Expect that an argument is matched exactly n times</td>
</tr>
<tr>
<td>times(n)</td>
<td>An alias for exactly(n)</td>
</tr>
<tr>
<td>times(n,m)</td>
<td>range multiplicity. Expect that an argument is matched at least n times, and at most m times. In the example here, the expectation is satisfied if the method is called with no arguments 1,2 or 3 times.</td>
</tr>
<tr>
<td>atLeast(n)</td>
<td>Expect that an argument is matched at least n times.</td>
</tr>
<tr>
<td>atMost(n)</td>
<td>Expect that an argument is matched at most n times. This argument is initially satisfied, and becomes unsatisfied if it matches more than n times.</td>
</tr>
</table>
<p>Note: <b>jqMock.expect</b> is the alias to the MultiplicityFactory</p>
<p>Example:</p>
<pre name="code" class="js:nocontrols:nogutter">
	mock.modify().args().multiplicity(expect.exactly(1));  
	mock.modify().args().multiplicity(expect.times(3));  
	mock.modify().args().multiplicity(expect.times(1,3));  
	mock.modify().args().multiplicity(expect.atLeast(1));  
	mock.modify().args().multiplicity(expect.atMost(4));  
</pre>
<br/><br/>



<h2><a name="ExpressionFactory">ExpressionFactory</a></h2>
<table class="api">
<tr><th>Function</th><th>Description</th></tr>
<tr>
<td>is.anything</td>
<td>always matches anything</td>
</tr>
<tr>
<td>is.not(x)</td>
<td>will match if the value is NOT the parameter</td>
</tr>
<tr>
<td>is.instanceOf(Class)</td>
<td>applies the instanceof operator, whether obj instanceof Class</td>
</tr>
<tr>
<td>is.regex(RegExp)</td>
<td>whether it matches the regex expression provided</td>
</tr>
<tr>
<td>is.anyOf([x1, x2, x3...])</td>
<td>matches one of the expressions in the array provided</td>
</tr>
<tr>
<td>is.allOf([x1, x2, x3...])</td>
<td>must match all of the expressions in the array provided. Useful for matching multiple not expressions</td>
</tr>
<tr>
<td>is.objectThatIncludes(object)</td>
<td>matches if the actual object has every field specified in the expected object</td>
</tr>
<tr>
<td>is.custom(Function)</td>
<td>specify a custom expression as a function that takes in a single argument and returns a boolean value</td>
</tr>
<tr>
<td><a name="isexception" class="ref">is.exception()</a></td>
<td>To be used with <a href="#expectThatExceptionThrown">expectThatExceptionThrown()</a>, matches any exception</b></td>
</tr>
<tr>
<td>is.exception(string)</td>
<td>To be used with <a href="#expectThatExceptionThrown">expectThatExceptionThrown()</a>, will assert that ex.message is equal to the parameter</b></td>
</tr>
<tr>
<td>is.exception({name: string, message: string, type: Class})</td>
<td>To be used with <a href="#expectThatExceptionThrown">expectThatExceptionThrown()</a>, will assert the values of ex.name and ex.message, and check that the exception is instanceof Class. Only the fields specified are checked.</b></td>
</tr>
</table>
<p>Note: <b>jqMock.is</b> is the alias to the ExpressionFactory</p>
<p>Example, assertThat:</p>
<pre name="code" class="js:nocontrols:nogutter">
	jqMock.assertThat(foo, is.anything);
	jqMock.assertThat(foo, is.not(100));
	jqMock.assertThat([1,2,3], is.instanceOf(Array));
	jqMock.assertThat("987", is.regex(/[0-9]*/)); 
	jqMock.assertThat(foo, is.anyOf(["a", "b", "c"]));
	jqMock.assertThat(foo, is.allOf([is.not(null), is.not(undefined)]));
	jqMock.assertThat({x:'x', a:'a', y:'y'}, is.objectThatIncludes({a:'a'}));

	function isEven(arg) {  
	    return arg % 2 == 0 ;  
	};  
	jqMock.assertThat(foo, is.custom(isEven));	
</pre>

<p>Example, mock.modify().args():</p>
<pre name="code" class="js:nocontrols:nogutter">
	var mock = new jqMock.Mock(myobj, "fn");

	mock.modify().args(is.anything);
	mock.modify().args(is.not(100));
	mock.modify().args(is.instanceOf(Array));	
	mock.modify().args(is.regex(/^abc[0-9]*xyz$/));
	mock.modify().args(is.anyOf(["a", "b", "c"]));
</pre>





<script type="text/javascript" src="highlighter/shCore.js"></script>
<script type="text/javascript" src="highlighter/shBrushJScript.js"></script>
<script type="text/javascript" src="highlighter/shBrushXml.js"></script>
<script type="text/javascript">
dp.SyntaxHighlighter.ClipboardSwf = 'highlighter/clipboard.swf';
dp.SyntaxHighlighter.HighlightAll('code');
</script>
</body>
</html>
